[AWS CDK] Bootstrap リソースのカスタマイズ（修飾子 `hnb659fds` の変更）をしてみた

こんにちは、CX事業本部 Delivery部の若槻です。

今回は、AWS CDK への Deep Dive の一環として、CDK の Bootstrap リソースをカスタマイズする方法を確認してみました。

AWS CDK の Bootstrap とは

AWS CDK によるリソースのデプロイは、AWS の環境（アカウントおよびリージョン）ごとに作成された Bootstrap リソースを使用して行われます。（これを Bootstrapping と言います）

Bootstrap リソースは AWS CDK Toolkit の　cdk bootstrap コマンドを使用して作成します。

デフォルトでは Bootstrap リソースは CDKToolkit というスタックで作成され、それらのリソースには hnb659fds という修飾子（Qualifier）が付与されます。

Bootstrap リソースをカスタマイズしてみる

何らかの理由により、デフォルトではない Bootstrap リソースを使用して CDK デプロイを行う必要が生じたとします。方法はいくつかあるのですが、手っ取り早いのは --toolkit-stack-name パラメーターおよび --qualifier パラメーターを指定する方法です。

--toolkit-stack-name では カスタムの Bootstrap リソースを作成するスタック名を指定します。これを指定することにより、デフォルトの CDKToolkit スタックを上書きせずに新規スタックを作成することができます。 --qualifier ではカスタムの Bootstrap リソースに付与する修飾子を指定します。これを指定することによりデフォルトの Bootstrap リソースとリソース名が重複することを防ぐことができます。

パラメーターを指定して Bootstrap コマンドを実行します。

$ cdk bootstrap --toolkit-stack-name myCDKToolkit --qualifier hoge
   Bootstrapping environment aws://XXXXXXXXXXXX/ap-northeast-1...
Trusted accounts for deployment: (none)
Trusted accounts for lookup: (none)
Using default execution policy of 'arn:aws:iam::aws:policy/AdministratorAccess'. Pass '--cloudformation-execution-policies' to customize.
myCDKToolkit: creating CloudFormation changeset...
   Environment aws://XXXXXXXXXXXX/ap-northeast-1 bootstrapped.

するとスタック名 myCDKToolkit 、修飾子 hoge で Bootstrap リソースが作成されました。

カスタマイズした Bootstrap リソースを使ってみる

デフォルトおよびカスタムともにステージング用のバケットを空にします。

$ aws s3 ls s3://cdk-hnb659fds-assets-${accountId}-ap-northeast-1

$ aws s3 ls s3://cdk-hoge-assets-${accountId}-ap-northeast-1

利用する Bootstrap リソースはスタックごとに制御が可能です。DefaultStackSynthesizer で qualifier プロパティを指定すると、指定した修飾子の Bootstrap リソースを使用することができます。

カスタムの Bootstrap リソースを使用するように CdkSampleStack を修正します。

import { App, DefaultStackSynthesizer } from 'aws-cdk-lib';
import { CdkSampleStack } from '../lib/cdk-sample-stack';

const app = new App();

new CdkSampleStack(app, 'CdkSampleStack', {
  synthesizer: new DefaultStackSynthesizer({
    qualifier: 'hoge',
  }),
});

デプロイ後に両ステージング用のバケットの内容を確認すると、カスタムの Bootstrap リソースが使用されていることが確認できました。

$ aws s3 ls s3://cdk-hnb659fds-assets-${accountId}-ap-northeast-1

$ aws s3 ls s3://cdk-hoge-assets-${accountId}-ap-northeast-1
2023-06-13 00:39:30       4011 39d56c558c679b9cdb48531ee4e47e412ae638e063a31f2980d7c6d2b2d909d6.json

両ステージング用バケットを再度空にして、次は qualifier プロパティを指定せずにスタックをデプロイしてみます。

import { App } from 'aws-cdk-lib';
import { CdkSampleStack } from '../lib/cdk-sample-stack';

const app = new App();

new CdkSampleStack(app, 'CdkSampleStack');

デプロイ後に両ステージング用のバケットの内容を確認すると、デフォルトの Bootstrap リソースが使用されていることが確認できました。

$ aws s3 ls s3://cdk-hnb659fds-assets-${accountId}-ap-northeast-1
2023-06-13 00:42:31       4016 a2419e6afa35f64faeeac7124b2489125c9309d332c341d7cb669af00c9d4d71.json
$ aws s3 ls s3://cdk-hoge-assets-${accountId}-ap-northeast-1

修飾子の指定によって、利用する Bootstrap リソースを切り替えることができました。

Qualifier は10文字以内である必要がある

11文字以上の値を指定すると Qualifier must be an alphanumeric identifier of at most 10 characters というエラーとなります。

$ cdk bootstrap --toolkit-stack-name myCDKToolkit --qualifier myqualifier
   Bootstrapping environment aws://XXXXXXXXXXXX/ap-northeast-1...
Trusted accounts for deployment: (none)
Trusted accounts for lookup: (none)
Using default execution policy of 'arn:aws:iam::aws:policy/AdministratorAccess'. Pass '--cloudformation-execution-policies' to customize.
myCDKToolkit: creating CloudFormation changeset...
   Environment aws://XXXXXXXXXXXX/ap-northeast-1 failed bootstrapping: Error [ValidationError]: Parameter Qualifier failed to satisfy constraint: Qualifier must be an alphanumeric identifier of at most 10 characters

おわりに

AWS CDK への Deep Dive の一環として、CDK の Bootstrap リソースをカスタマイズする方法を確認してみました。AWS CDK の裏側の仕組みを一部垣間見ることができました。

正直、Bootstrap リソースをカスタマイズして分離する必要性が生じることは殆どないと思います。（Bootstrap version のアップデートの検証や、スタックごとにデプロイ時の権限を極めて細かく制御したい場合などでしょうか。）

以上